home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 016a / love4th.zip / LOCALVAR.DOC < prev    next >
Text File  |  1991-10-01  |  7KB  |  170 lines
  1.                Local Variables in L.O.V.E. Forth
  2.                =================================
  3.  
  4. Stack Manipulation
  5. ------------------
  6.  
  7. Forth source code has been criticized by many as unreadable. This is due to
  8. the traditional use of stack manipulation operators (such as swap, dup,
  9. rot, pick, roll etc... ) rather than the reverse polish syntax. Incorrect
  10. manipulation of the parameter stack in Forth is such a frequent source of
  11. logical bugs that experienced Forth programmers habitually insert 'stack
  12. diagrams' beside their phrases to document the net effect on the stack. The
  13. problem of ordering data items on the stack is compounded by the use of
  14. double and quad length items to represent pointers of different sizes,
  15. large valued integers and floating point numbers. In an attempt to remedy
  16. this, many versions of local variables and named parameters have been
  17. implemented by Forth programmers. The implementation for L.O.V.E. Forth 
  18. has a syntax modelled after that used in a Forth-83 system for the 
  19. Apple Macintosh called MACH-2 by Palo Alto Shipping Company.
  20.  
  21.  
  22.  
  23. Benefits
  24. --------
  25.  
  26. Local variables and named input parameters are an addition to the
  27. L.O.V.E. Forth compiler that improves the readability of source code 
  28. and allows the programmer to spend less time thinking about the order 
  29. and sizes of data items on Forth's parameter stack. An additional and 
  30. significant benefit is increased execution speed and decreased object 
  31. code size. Local variables and named input parameters insulate the 
  32. implementation of a definition from changes to the order and data types 
  33. of the input parameters, are used at the programmers discretion and are 
  34. entirely optional.
  35. This implementation of local variables allows the programmer to write 
  36. completely re-entrant code and recursive definitions with ease.
  37.  
  38.  
  39. Usage
  40. -----
  41.  
  42.  
  43. The syntax used replaces the traditional stack diagram after the name of
  44. the new definition.
  45.  
  46. Local variables and named input parameters have a structure following this
  47. general form:
  48.  
  49.  
  50. : aname  { [type] n1 [type] n2 ... [type] n? | [type] L1  ... [type] L? -- comment }
  51.         ...  ;
  52.  
  53. where:
  54.  
  55. '{'       is an immediate word that precedes a locxal variable specification
  56.           list and parses this information up to the first '}' and must be used
  57.           immediately after the name of the new definition.
  58.  
  59.  
  60. [type]    is a built in type specifier that tells the parser how to compile
  61.           object code for the local variable name following it in the local
  62.           variable specification.
  63.           Available types are:
  64.  
  65.                 word:   -- a two byte (word length) integer
  66.                 long:   -- a four byte (long word length) integer
  67.                 quad:   -- an eight byte (quad word length) integer
  68.                 float:  -- a four byte (single precision) floating point value
  69.                            in IEEE single precision format
  70.                 double: -- an eight byte (double precision) floating point
  71.                            value in IEEE double precision format
  72.                 ext:    -- a ten byte (extended precision) floating point
  73.                            value in IEEE extended precision format
  74.                 fbcd:   -- a ten byte (binary coded decimal) floating point
  75.                            value in 80x87 BCD format
  76.  
  77.         ** NOTE : If a local variable name appears without a type specifier
  78.                   the parser assumes that it is a 'word:' type. This allows
  79.                   the programmer to write simple definitions using mostly word
  80.                   length items without always specifying the 'word:' type.
  81.  
  82.  
  83. n1 n2 n3 ...        are named input parameters from the stack where n1 is
  84.                     deepest in the stack and n? is on the top of the
  85.                     parameter stack.
  86.  
  87. | (bar)             is a separator character that terminates the input variable
  88.                     list and signals that a local variable list will begin.
  89.  
  90. L1 L2 L3 ...        is the list of local variable names used in this
  91.                     definition.
  92.  
  93. --                  specifies that a comment begins, a comment string follows,
  94.                     usually used to document what the definition leaves on the
  95.                     stack. May not contain '}'  .
  96.  
  97.  
  98.  
  99. Notes:
  100.  
  101. (1)    Named parameters, temporary local variables and the comment are all
  102.        optional. A definition with no input parameters can have local
  103.        variables for temporary results.
  104.  
  105. (2)    In the V1.24 implementation a local variable stack frame can contain up
  106.        to 128 bytes of named input parameters and temporary local variables
  107.        (one local frame per definition).
  108.  
  109. (3)    Local names can be any space delimited string up to 31 characters
  110.        long but must not be named '|' (bar) or '--' (comment) or '}' (left
  111.        brace) or given a name that is identical to a type specifier .
  112.  
  113.  
  114. Examples
  115. --------
  116.  
  117.  
  118.           : <a_word>   { arg1 arg2 arg3  | temp  -- result }
  119.                ...............
  120.                ...............   ;
  121.  
  122.  
  123.  
  124. The named arguments 'arg1', 'arg2' and 'arg3' are initialized values on the
  125. parameter stack with 'arg3' on the top and 'arg1' deepest on the stack. The
  126. local variable 'temp' is an uninitialized temporary value.
  127.  
  128.           : <b_word>   { word: arg1   long: arg2   | ext: temp  -- result }
  129.                ...............
  130.                ...............   ;
  131.  
  132.  
  133.  
  134. The named arguments 'arg1', 'arg2' are initialized values on the
  135. parameter stack with long word length 'arg2' on the top and word length 'arg1'
  136. deepest on the stack. The local variable 'temp' is an uninitialized extended
  137. precision floating point temporary value.
  138.  
  139.  
  140.  
  141.  
  142. Operations with Local Variables
  143. -------------------------------
  144.  
  145. There are 4 basic operations with local variables and the possibility of
  146. adding more operations in the future.
  147. These operations are:
  148.  
  149.        local_name    -- the default action of a local variable is to fetch
  150.                             the contents of the local variable to the top
  151.                             of the stack.
  152.  
  153.        -> local_name -- stores the top of stack into the location specified by
  154.                         local_name in the format specified by the type of
  155.                         local_name.
  156.  
  157.        +> local_name -- adds the top of stack to the contents of the location
  158.                         specified by local_name in the format specified by the
  159.                         type of local_name.
  160.  
  161.        & local_name  -- returns the segment and offset of the contents of
  162.                             local_name.
  163.  
  164.  
  165.  
  166.  
  167. All operations with local variables are immediate words that determine at
  168. compile time what type of data will be operated upon and then compile the
  169. correct object code.
  170.